DeepWiki

08.a - Environment-Variables

Relevant source files

This page documents all environment variables required to configure and run the godeep.wiki application. Environment variables control authentication, payment processing, notifications, and application behavior. For instructions on deploying these variables to production, see Deployment Guide. For details on how to obtain GitHub App credentials, see GitHub App Configuration.

The application uses environment variables for:

  • GitHub App authentication (both user OAuth and owner installation tokens)
  • Stripe payment processing (checkout sessions and webhook verification)
  • Admin panel access (password-based authentication)
  • Event notifications (ntfy.sh message broker)
  • Analytics integration (optional Cloudflare monitoring)

Environment variables are loaded from .env files during development and configured in the hosting platform (Vercel) for production deployments. The .env.example file provides a template showing all required variables.

Sources: .env.example L1-L15

CLAUDE.md L86-L108

README.md L71-L91

The following diagram shows how environment variables are organized by system component and their usage throughout the application:

Environment Variable Distribution Across System Components

Sources: .env.example L1-L15

CLAUDE.md L86-L108

These variables configure the GitHub App integration that enables both user OAuth authentication and owner repository access via installation tokens.

VariableRequiredPurposeWhere Used
GITHUB_APP_SLUGYesGitHub App slug for installation URL constructionapi/auth/github
GITHUB_APP_IDYesNumeric GitHub App ID for JWT creationlib/github-app.ts
GITHUB_CLIENT_IDYesOAuth client ID for user authenticationapi/auth/github
GITHUB_CLIENT_SECRETYesOAuth client secret for token exchangeapi/auth/github/callback

GITHUB_APP_SLUG

The slug appears in the GitHub App installation URL: https://github.com/apps/{GITHUB_APP_SLUG}/installations/new. This variable is used to construct the OAuth redirect URL that initiates the GitHub App installation flow.

Example value: godeepwiki-github-integration

GITHUB_APP_ID

The numeric identifier for your GitHub App, found in the app settings under "About". This ID is used to create GitHub App JWTs when generating installation access tokens, which allow the owner to access customer repositories.

Example value: 123456

GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET

These OAuth credentials enable user authentication and are used during the OAuth code exchange to obtain user access tokens. The client ID is embedded in OAuth URLs, while the client secret is used server-side to exchange authorization codes for access tokens.

Example client ID: Iv1.abc123def456

Sources: .env.example L1-L4

CLAUDE.md L90-L96

README.md L76-L79

VariableRequiredPurposeWhere Used
GITHUB_PRIVATE_KEYYesPEM-formatted private key for GitHub App JWT signinglib/github-app.ts

The private key is used to sign JWTs that authenticate as the GitHub App itself. This enables the generation of installation access tokens, which are required for the owner to clone and access customer repositories.

Format Requirements:

  • PEM format (begins with -----BEGIN RSA PRIVATE KEY-----)
  • Can be stored as multiline string in Vercel
  • For single-line .env files, base64 encode: cat key.pem | base64

How to Obtain:

  1. Navigate to your GitHub App settings
  2. Scroll to "Private keys" section
  3. Click "Generate a private key"
  4. Download the .pem file
  5. Copy contents to environment variable (preserve newlines in Vercel)

Sources: .env.example L5

CLAUDE.md L94

CLAUDE.md L213-L221

VariableRequiredPurposeWhere Used
GITHUB_WEBHOOK_SECRETOptionalSecret for verifying webhook signaturesapi/webhooks/github

This secret enables signature verification for GitHub webhook events, providing an additional logging mechanism for installation tracking. While optional, it's recommended for redundant event capture.

How to Generate:

openssl rand -hex 32

Save the generated value to both your .env file and your GitHub App webhook configuration.

Sources: .env.example L6

CLAUDE.md L96

CLAUDE.md L163-L166

These variables configure Stripe integration for payment processing and webhook verification.

VariableRequiredPurposeWhere Used
STRIPE_SECRET_KEYYesServer-side Stripe API key for checkout session creationapp/actions.ts
STRIPE_PUBLISHABLE_KEYYesServer-side publishable key (legacy, for reference)-
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEYYesClient-accessible publishable keyapp/actions.ts
STRIPE_WEBHOOK_SECRETYesWebhook signature verification secretapi/webhooks/stripe
STRIPE_MCP_KEYOptionalAdditional Stripe integration key-

Key Types and Usage:

The diagram below shows how different Stripe keys are used throughout the payment flow:

Stripe Key Usage in Payment Flow

STRIPE_SECRET_KEY

Server-side secret key used to create checkout sessions via the Stripe API. This key must never be exposed to the client. Format: sk_live_... (production) or sk_test_... (testing).

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY

Client-accessible publishable key used in the checkout session creation flow. This key is safe to expose in client-side code. Format: pk_live_... (production) or pk_test_... (testing).

STRIPE_WEBHOOK_SECRET

Secret used to verify webhook signatures from Stripe. This ensures that webhook events are authentic and originate from Stripe. Format: whsec_...

How to Obtain:

  1. Navigate to Stripe Dashboard → Developers → API keys
  2. Copy "Publishable key" and "Secret key"
  3. For webhook secret: Developers → Webhooks → Add endpoint
  4. Set endpoint URL to https://your-domain.com/api/webhooks/stripe
  5. Select event type: checkout.session.completed
  6. Copy the signing secret after creation

Sources: .env.example L9-L13

CLAUDE.md L102-L105

README.md L85-L87

These variables control application-level behavior and authentication.

VariableRequiredPurposeWhere Used
NEXT_PUBLIC_APP_URLYesBase URL for OAuth callbacks and redirectsapi/auth/github
app/actions.ts

This variable defines the application's base URL and is used to construct OAuth callback URLs and Stripe redirect URLs. It must match your deployment URL exactly.

Example values:

  • Development: http://localhost:3000
  • Production: https://godeep.wiki

Critical Usage:

  • OAuth callback URL construction: ${NEXT_PUBLIC_APP_URL}/api/auth/github/callback
  • Stripe success URL: ${NEXT_PUBLIC_APP_URL}/success?session_id={CHECKOUT_SESSION_ID}

Sources: .env.example L7

CLAUDE.md L99

README.md L82

VariableRequiredPurposeWhere Used
NEXT_PUBLIC_ADMIN_PASSWORDYesPassword for admin panel accessadmin
api/admin/generate-token
automation scripts

This password protects the admin panel at /admin, which is used to generate installation access tokens for accessing customer repositories.

Security Consideration: The NEXT_PUBLIC_ prefix makes this variable accessible to client-side code, which is unusual for sensitive credentials. The system uses a simple password-based authentication model suitable for single-owner operation, not enterprise-grade security. Consider this when choosing the password value.

Usage Flow:

  1. Owner navigates to /admin
  2. Enters password (verified client-side and server-side)
  3. Session stored in localStorage
  4. Password also used by automation scripts to call token generation API

Sources: .env.example L8

CLAUDE.md L100

CLAUDE.md L169-L184

VariableRequiredPurposeWhere Used
NTFY_TOPICYesntfy.sh topic name for event notificationsapi/webhooks/stripe
api/auth/github/callback
automation scripts

The ntfy.sh topic serves as a message broker between payment/installation events and the automation scripts that clone repositories. This enables event-driven automation without requiring a database or message queue service.

Topic Structure:

The topic name should be unique to prevent unauthorized access. Example: godeep-wiki-payments or klaudioz-codex-alerts-2024.

Event Flow:

Notification Payload Example:

{  "title": "GitHub Connected",  "message": "Installation: 12345678, Match ID: abc123...",  "tags": ["white_check_mark"]}

The automation scripts subscribe to this topic and trigger repository cloning when notifications arrive.

Sources: .env.example L14

CLAUDE.md L163-L166

VariableRequiredPurposeWhere Used
NEXT_PUBLIC_CF_BEACON_TOKENNoCloudflare Web Analytics beacon tokenapp/layout.tsx

Enables Cloudflare Web Analytics for privacy-focused visitor tracking without cookies. If omitted, no analytics tracking is enabled.

How to Obtain:

  1. Create Cloudflare account
  2. Navigate to Web Analytics
  3. Add a site
  4. Copy the beacon token

Sources: .env.example L15

CLAUDE.md L108

README.md L89-L90

The following diagram illustrates the security characteristics of different environment variable categories:

Security Model for Environment Variables

Server-Side Variables:

  • Store securely in Vercel environment (not in .env committed to git)
  • Rotate secrets regularly (especially after team changes)
  • Use separate keys for development/staging/production

Client-Accessible Variables:

  • Only use NEXT_PUBLIC_ prefix for truly public values
  • Never include secrets or API keys in public variables
  • Understand these values are visible in browser DevTools

Admin Password:

  • Choose a strong, unique password (20+ characters recommended)
  • Do not reuse passwords from other services
  • Consider implementing IP allowlisting for /admin in production
  • Be aware this is not suitable for multi-user scenarios

Sources: CLAUDE.md L110-L122

README.md L393-L401

# GitHub App ConfigurationGITHUB_APP_SLUG=godeepwiki-github-integrationGITHUB_APP_ID=123456GITHUB_CLIENT_ID=Iv1.abc123def456GITHUB_CLIENT_SECRET=abc123def456xyz789GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----MIIEpAIBAAKCAQEA...-----END RSA PRIVATE KEY-----"GITHUB_WEBHOOK_SECRET=abc123def456xyz789abc123def456xyz789abc123def456xyz789abc123def4# Application SettingsNEXT_PUBLIC_APP_URL=http://localhost:3000NEXT_PUBLIC_ADMIN_PASSWORD=your-secure-admin-password-here# Stripe Configuration (Test Mode)STRIPE_PUBLISHABLE_KEY=pk_test_abc123NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_abc123STRIPE_SECRET_KEY=sk_test_xyz789STRIPE_WEBHOOK_SECRET=whsec_test123# Notification SystemNTFY_TOPIC=godeep-wiki-payments-dev# Optional AnalyticsNEXT_PUBLIC_CF_BEACON_TOKEN=

For production deployment, configure environment variables in the Vercel dashboard:

  1. Navigate to Project Settings → Environment Variables
  2. Add each variable with appropriate scope (Production/Preview/Development)
  3. Use multiline text for GITHUB_PRIVATE_KEY (preserve newlines)
  4. Mark sensitive variables as "Encrypted" in Vercel

Vercel CLI Configuration:

vercel env add GITHUB_CLIENT_SECRET productionvercel env add STRIPE_SECRET_KEY productionvercel env add GITHUB_PRIVATE_KEY production

Sources: README.md L276-L289

CLAUDE.md L86-L108

The automation scripts (ntfy-godeep-automation.sh and ntfy-godeep-automation-remote.sh) require specific environment variables to be set in the shell environment where they run:

Required Variables:

export ADMIN_PASSWORD="your-secure-admin-password"export NTFY_TOPIC="godeep-wiki-payments"export APP_URL="https://godeep.wiki"

These scripts subscribe to the ntfy.sh topic and use the admin password to authenticate with the token generation API when processing notifications.

Sources: Inferred from architecture diagrams and system design

The application performs basic validation on environment variables at startup. Missing required variables will cause build failures or runtime errors:

Critical Variables Checked:

  • GITHUB_CLIENT_ID - Required for OAuth initialization
  • GITHUB_CLIENT_SECRET - Required for token exchange
  • GITHUB_APP_ID - Required for installation token generation
  • GITHUB_PRIVATE_KEY - Required for JWT signing
  • STRIPE_SECRET_KEY - Required for checkout session creation
  • NEXT_PUBLIC_APP_URL - Required for OAuth callback URL construction

Validation Locations:

Sources: Inferred from code structure and error handling patterns

For information on how to obtain GitHub App credentials, see GitHub App Configuration. For deployment instructions and how to configure these variables in production, see Deployment Guide.

Refresh this wiki

Last indexed: 23 November 2025 (922b35)

On this page

Ask Devin about godeep.wiki-jb

Syntax error in text

mermaid version 11.4.1

08.a - Environment-Variables | DeepWiki | godeep.wiki